README.txt for ATC-NY Windows Memory Reader (WMR) [tm]
------------------------------------------------------

Copyright (c) 2011-2012 Architecture Technology Corporation.
All rights reserved.


Windows Memory Reader generates either a Windows crash dump file or a
raw file of the contents of a running system's physical memory (RAM).
It is intended to be run directly on the target machine, with output to a
USB drive or similar.  You must be familiar with running command line tools
to use this program.  You should also be aware of the forensic implications
of running a process (in RAM) to gather the contents of that same RAM.

Windows Memory Reader runs on 32- and 64-bit versions of Windows XP,
Windows Server 2003, Windows Vista, Windows Server 2008, Windows 7,
and Windows 8.

See LICENSE.txt for license information.

If you are interested in a full-featured forensic suite that includes
RAM analysis capabilities, see Mem Marshal:  http://www.memmarshal.com/

Web site:
http://www.cybermarshal.com/index.php/cyber-marshal-utilities/windows-memory-reader

Please email support@memmarshal.com or use the 'support' section of the web
site above if you've found a problem with the software.

If you need to capture RAM on a Mac, try Mac Memory Reader:
http://www.cybermarshal.com/index.php/cyber-marshal-utilities/mac-memory-reader


Usage
-----

1. Ensure you have an external drive with sufficient space for the RAM image.
   Note that most USB drives are formatted as FAT-32, which limits files to
   4GB in size.  ExFAT and NTFS do not have this file size restriction.
   See below for other workarounds if you must save to a FAT-32 drive.

2. When ready to image, mount the drive (by plugging it in) and execute the
   Windows Command Prompt (cmd.exe) in administrator mode.  In Windows Vista
   and later, this can be done by typing "cmd" in the search box in the Start
   menu and right clicking on the cmd result, then selecting "Run as
   administrator."  In Windows XP/2003, cmd is always run in administrative
   mode when run by an administrative user.

3. Move to the external drive with the wmr.exe executable. Use "cd <drive>".

4. Execute the Windows Memory Reader by typing:
      wmr <filename>
   where <filename> is the path to write memory to, such as
   D:\STORAGE\ram_dump.dmp.  Various options can be added before the file name;
   these are described below.
   
The output file may be slightly larger than physical memory due to the Windows
Crash Dump header and block alignment constraints.  If the filename is '-',
memory is dumped to stdout.

If you are saving the RAM snapshot to a FAT-32 formatted USB drive, FAT-32's
file size restrictions will prevent you from writing RAM snapshots that are
4GB or larger.  To get around this limitation, you must run wmr from a
Unix-like environment such as MinGW or Cygwin.  You can then split the output
into multiple 2GB chunks on the fly files using a command line such as the
following:
  wmr - | split -b 2048m - ram_dump.dmp.
This will create ram_dump.dmp.aa, ram_dump.dmp.ab, etc.
If you don't want to split the file, consider using an ExFAT or NTFS-formatted
drive.

You can also send the RAM snapshot to a remote machine over the network; this
also requires running wmr from a Unix-like environment such as MinGW or Cygwin.
To send it to a raw TCP socket on port 'portnum' on host 'hostname' using
netcat:
  wmr - | nc hostname portnum
To send it encrypted as a file to a host running SSH:
  wmr - | ssh hostname cat \> /path/to/remote/destfile

Normally, Windows Memory Reader saves RAM snapshots in Windows Crash Dump
format, which includes a table of contents and system information followed by
the raw data.  Adding the '-p' flag to wmr will change the output format to a
plain/raw DD style, with only the bytes of physical memory and no header
information.  Because the raw format does not preserve memory region
information (types and offsets), wmr will print a table of contents when done.
Adding '-P' instead will cause unused memory regions to be zero-filled,
removing the need for the table of contents but causing the RAM snapshot to
(potentially) require significantly more disk space than the size of RAM.

Windows Memory Reader can compute hashes on the fly if needed: add
'-H hashtype' arguments (where hashtype is one of MD5, SHA-1, SHA-256, or
SHA-512) to have hashes printed on stderr.  For example,
'wmr -H MD5 -H SHA-1 ...' will compute both MD5 and SHA-1 hashes of the memory
dump.

Adding the -d flag to wmr will give verbose diagnostic information as the RAM
snapshot is being written.

'wmr -h' gives the full set of command-line options.



Interpreting the Results
------------------------

Windows Memory Reader is designed to work with Mem Marshal, Volatility, or
other physical memory analysis applications.

In addition, hex editors, string extraction tools, search tools, and file
carvers are all useful for extracting data.  Aside from the file header,
Windows Crash Dump files are simply raw data files, simplifying search and data
extraction.  (If you use the Unix-style command-line program 'strings' to
examine the file, be aware that it treats object files specially and only
examines part of the file by default.  Use the '-' option to force strings
to examine the whole file. For example, 'strings - ram_dump.dmp')

Some versions of the Unix 'strings' command try to map the entire file they're
reading into memory.  You may get "cannot allocate memory" errors if either
  1 - the machine you're analyzing RAM on has less physical memory than
      the machine from which the snapshot was taken, or
  2 - the snapshot you're analyzing RAM on is running a 32-bit kernel
      and the snapshot was taken on a machine running 64-bit Windows.
To run 'strings' anyway, you can force it to not map the entire file at
once: "cat ram_dump.dmp | strings - -"

Programmers wishing to experiment with mapped device memory may be interested
in Windows Memory Reader's -D or -r flags.  They can give you access to
non-RAM "memory" pages or I/O devices such as video cards.

Important note: Pieces of the wmr executable code and data will certainly
appear within the RAM snapshot, simply because Windows Memory Reader is
running in the same memory space being acquired.  This is a known "footprint"
and aspect of live analysis.


Implementation Notes
--------------------

Windows Memory Reader records all available physical memory regions, excluding
memory-mapped devices and other reserved regions.  If -r or --copy-reserved is
used, Windows Memory Reader also copies these regions but may crash the
machine (due to "reading" from I/O devices that do not expect reads).  It
is highly recommended to use the interactive mode (-i or --interactive)
in conjunction with -r so that you can pick regions to dump.  On machines
with shared video RAM, this technique can be used to record video memory.

Windows Memory Reader uses the \Device\PhysicalMemory and ZwMapViewOfSection()
method of reading memory in the Windows kernel.  It also tries the
MmMapIoSpace() method on any pages that fail.  Unlike many memory dump tools,
it does acquire the "page zero" of RAM, between 0x0000 and 0x1000, which is not
normally in the physical memory map maintained by the Windows kernel.
 

Changes
-------

Version 1.0

- initial release
